From 9873d983ed0a4b4b374515d8d818d50b0aff0299 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 23 May 2020 21:32:35 -0400 Subject: [PATCH] docs: Convert css overview to markdown --- docs/reference/gtk/css-overview.md | 79 ++ docs/reference/gtk/css-overview.xml | 1179 -------------------------- docs/reference/gtk/css-properties.md | 238 ++++++ docs/reference/gtk/gtk4-docs.xml | 1 + docs/reference/gtk/meson.build | 5 +- 5 files changed, 321 insertions(+), 1181 deletions(-) create mode 100644 docs/reference/gtk/css-overview.md delete mode 100644 docs/reference/gtk/css-overview.xml create mode 100644 docs/reference/gtk/css-properties.md diff --git a/docs/reference/gtk/css-overview.md b/docs/reference/gtk/css-overview.md new file mode 100644 index 0000000000..9c1fad71eb --- /dev/null +++ b/docs/reference/gtk/css-overview.md @@ -0,0 +1,79 @@ +# CSS in GTK {#css} + +This chapter describes how GTK uses CSS for styling and layout. +It is not meant to be an explanation of CSS from first principles, +but focuses on listing supported CSS features and differences +between Web CSS and GTK. + +There is plenty of introductory documentation available that +can be used to learn about CSS in general. In the tables below +we include links to the official specs that can be used to look +up the definition of individual selectors and properties. + +## CSS nodes + +GTK applies the style information found in style sheets by matching +the selectors against a tree of nodes. Each node in the tree has a +name, a state and possibly style classes. The children of each node +are linearly ordered. + +Every widget has one or more of these CSS nodes, and determines their +name, state, style classes and how they are layed out as children and +siblings in the overall node tree. The documentation for each widget +explains what CSS nodes it has. + +### The CSS nodes of a GtkScale + +``` +scale[.fine-tune] +├── marks.top +│ ├── mark +┊ ┊ +│ ╰── mark +├── trough +│ ├── slider +│ ├── [highlight] +│ ╰── [fill] +╰── marks.bottom + ├── mark + ┊ + ╰── mark +``` + +## Selectors + +Selectors work very similar to the way they do on the web. + +All widgets have one or more CSS nodes with element names and style +classes. When style classes are used in selectors, they have to be prefixed +with a period. Widget names can be used in selectors like IDs. When used +in a selector, widget names must be prefixed with a # character. + +### GTK CSS Selectors + +| Pattern | Reference | Notes | +|:--------|:----------|:------| +| * | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#universal-selector) | | +| E | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#type-selectors) | | +| E.class | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#class-html) | | +| E#id | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#id-selectors) | | +| E:nth-child(n) | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#structural-pseudos) | | +| E:nth-last-child(n) | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#structural-pseudos) | | +| E:first-child | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#structural-pseudos) | | +| E:last-child | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#structural-pseudos) | | +| E:only-child | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#structural-pseudos) | | +| E:link, E:visited | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#link) | Corresponds to GTK_STATE_FLAG_LINK and GTK_STATE_FLAGS_VISITED | +| E:active, E:hover, E:focus | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#useraction-pseudos) | Correspond to GTK_STATE_FLAG_ACTIVE, GTK_STATE_FLAG_PRELIGHT, GTK_STATE_FLAGS_FOCUSED | +| E:focus-within | [CSS Selector Level 4](https://drafts.csswg.org/selectors/#focus-within-pseudo) | Set on all ancestors of the focus widget, unlike CSS | +| E:focus-visible | [CSS Selector Level 4](https://drafts.csswg.org/selectors/#focus-within-pseudo) | Set on focus widget and all ancestors, unlike CSS | +| E:disabled | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#UIstates) | Corresponds to GTK_STATE_FLAG_INSENSITIVE | +| E:disabled | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#UIstates) | Corresponds to GTK_STATE_FLAG_CHECKED | +| E:indeterminate | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#indeterminate) | Corresponds to GTK_STATE_FLAG_INCONSISTENT | +| E:backdrop, E:selected | | Corresponds to GTK_STATE_FLAG_BACKDROP, GTK_STATE_FLAG_SELECTED | +| E:not(selector) | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#negation) | | +| E:dir(ltr), E:dir(rtl) | [CSS Selector Level 4](https://drafts.csswg.org/selectors/#the-dir-pseudo) | | +| E:drop(active) | [CSS Selector Level 4](https://drafts.csswg.org/selectors/#drag-pseudos) | | +| E F | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#descendent-combinators) | | +| E > F | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#child-combinators) | | +| E ~ F | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#general-sibling-combinators) | | +| E + F | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#adjacent-sibling-combinators) | | diff --git a/docs/reference/gtk/css-overview.xml b/docs/reference/gtk/css-overview.xml deleted file mode 100644 index 67f32d6731..0000000000 --- a/docs/reference/gtk/css-overview.xml +++ /dev/null @@ -1,1179 +0,0 @@ - - - - -GTK CSS Overview -3 -GTK Library - - - -GTK CSS Overview - -The language used for style information in GTK - - - - - CSS in GTK - - - This chapter describes how GTK uses CSS for styling and layout. - It is not meant to be an explanation of CSS from first principles, - but focuses on listing supported CSS features and differences - between Web CSS and GTK. - - - - There is plenty of introductory documentation available that - can be used to learn about CSS in general. In the tables below - we include links to the official specs that can be used to look - up the definition of individual selectors and properties. - - - - CSS nodes - - - GTK applies the style information found in style sheets by matching - the selectors against a tree of nodes. Each node in the tree has a - name, a state and possibly style classes. The children of each node - are linearly ordered. - - - - Every widget has one or more of these CSS nodes, and determines their - name, state, style classes and how they are layed out as children and - siblings in the overall node tree. The documentation for each widget - explains what CSS nodes it has. - - - - The CSS nodes of a GtkScale - - - - - - - Selectors - - - Selectors work very similar to the way they do on the web. - - - - All widgets have one or more CSS nodes with element names and style - classes. When style classes are used in selectors, they have to be prefixed - with a period. Widget names can be used in selectors like IDs. When used - in a selector, widget names must be prefixed with a # character. - - - - GTK CSS Selectors - - - PatternReferenceNotes - - - - * - CSS Selectors Level 3 - - - - E - CSS Selectors Level 3 - - - - E.class - CSS Selectors Level 3 - - - - - E#id - CSS Selectors Level 3 - GTK uses the widget name as ID - - - E:nth-child(nth-child) - CSS Selectors Level 3 - - - - E:nth-last-child(nth-child) - CSS Selectors Level 3 - - - - E:first-child - CSS Selectors Level 3 - - - - E:last-child - CSS Selectors Level 3 - - - - E:only-child - CSS Selectors Level 3 - Equivalent to E:first-child:last-child - - - E:link, E:visited - CSS Selectors Level 3 - Corresponds to GTK_STATE_FLAG_LINK and GTK_STATE_FLAGS_VISITED - - - E:active, E:hover, E:focus - CSS Selectors Level 3 - Correspond to GTK_STATE_FLAG_ACTIVE, GTK_STATE_FLAG_PRELIGHT, GTK_STATE_FLAGS_FOCUSED - - - E:focus-within - CSS Selectors Level 4 - Set on all ancestors of the focus widget, unlike CSS - - - E:focus-visible - CSS Selectors Level 4 - Set on focus widget and all ancestors, unlike CSS - - - E:disabled - CSS Selectors Level 3 - Corresponds to GTK_STATE_FLAG_INSENSITIVE - - - E:checked - CSS Selectors Level 3 - Corresponds to GTK_STATE_FLAG_CHECKED - - - E:indeterminate - CSS3 Selectors Level 3 - Corresponds to GTK_STATE_FLAG_INCONSISTENT - - - E:backdrop, E:selected - - Corresponds to GTK_STATE_FLAG_BACKDROP, GTK_STATE_FLAG_SELECTED - - - E:not(selector) - CSS Selectors Level 3 - - - - E:dir(ltr), E:dir(rtl) - CSS Selectors Level 4 - - - - E:drop(active) - CSS Selectors Level 4 - - - - E F - CSS Selectors Level 3 - - - - E > F - CSS Selectors Level 3 - - - - E ~ F - CSS Selectors Level 3 - - - - E + F - CSS Selectors Level 3 - - - - -
- - - - - - - GTK CSS Properties - - - GTK supports CSS properties and shorthands as far as they can be applied - in the context of widgets, and adds its own properties only when needed. - All GTK-specific properties have a -gtk prefix. - - - - Basic types - - - All properties support the following keywords: inherit, initial, unset, with - the same meaning as defined in the CSS Cascading and Inheritance spec. - - - - The following units are supported for basic datatypes: - - - - - Length px, pt, em, ex, rem, pc, in, cm, mm, calc() - - - Percentage %, calc() - - - Angle deg | grad | turn, calc() - - - Time s | ms, calc() - - - - - Length values with the em or ex units are resolved using the font - size value, unless they occur in setting the font-size itself, in - which case they are resolved using the inherited font size value. - - - - The rem unit is resolved using the initial font size value, which is - not quite the same as the CSS definition of rem. - - - - The calc() notation adds considerable expressive power. There are limits - on what types can be combined in such an expression (e.g. it does not make - sense to add a number and a time). For the full details, see the - CSS3 Values and - Units spec. - - - - A common pattern among shorthand properties (called 'four sides') is one - where one to four values can be specified, to determine a value for each - side of an area. In this case, the specified values are interpreted as - follows: - - - 4 values: top right bottom left - - - 3 values: top horizontal bottom - - - 2 values: vertical horizontal - - - 1 value: all - - - - - - - - Colors - - - GTK extends the CSS syntax with several additional ways to specify colors. - - - The first is a reference to a color defined via a @define-color rule in CSS. - The syntax for @define-color rules is as follows: - - @define-color Name Color - - - - To refer to the color defined by a @define-color rule, prefix the name with @. - - - GTK also supports color expressions, which allow colors to be transformed to - new ones. Color expressions can be nested, providing a rich language to - define colors. Color expressions resemble functions, taking 1 or more colors - and in some cases a number as arguments. - - lighter(Color) produces a brigher variant of Color - darker(Color) produces a darker variant of Color - shade(Color, Number) changes the lightness of Color. The number ranges from 0 for black to 2 for white. - alpha(Color, Number) replaces the alpha value of color with number (between 0 and 1) - mix(Color1, Color2, Number) interpolates between the two colors - - - - - - Images - - GTK extends the CSS syntax for images and also uses it for specifying icons. - To load a themed icon, use - - -gtk-icontheme(Name) - - The specified icon name is used to look up a themed icon, while taking into - account the values of the -gtk-icon-palette property. - This kind of image is mainly used as value of the -gtk-icon-source property. - - - Symbolic icons from the icon theme are recolored according to the - -gtk-icon-palette property, which defines a list of named colors. - The recognized names for colors in symbolic icons are error, warning - and success. The default palette maps these three names to symbolic - colors with the names @error_color, @warning_color and @success_color - respectively. The syntax for defining a custom palette is a comma-separated - list of name-color pairs, e.g. - - success blue, warning #fc3, error magenta - - - - Recoloring is sometimes needed for images that are not part of an icon theme, - and the - - -gtk-recolor(uri, palette) - - syntax makes this available. -gtk-recolor requires a url as first argument. - The remaining arguments specify the color palette to use. If the palette is - not explicitly specified, the current value of the -gtk-icon-palette property - is used. - - - GTK supports scaled rendering on hi-resolution displays. This works best if - images can specify normal and hi-resolution variants. From CSS, this can be - done with - - -gtk-scaled(Image1, Image2) - - - - - - - GTK CSS Properties - - - - - - - Color and Filter Properties - NameReferenceNotes - - - - color - - CSS Color Level 3 - - - - - opacity - - CSS Color Level 3 - - - - - filter - - CSS Filter Effects Level 1 - - - - Font Properties - - font-family - - CSS Fonts Level 3 - - defaults to gtk-font-name setting - - - font-size - - CSS Fonts Level 3 - - defaults to gtk-font-name setting - - - font-style - - CSS Fonts Level 3 - - - - - font-variant - - CSS Fonts Level 3 - - only CSS2 values supported - - - font-weight - - CSS Fonts Level 3 - - - - - font-stretch - - CSS Fonts Level 3 - - - - - font-kerning - - CSS Fonts Level 3 - - - - - font-variant-ligatures - - CSS Fonts Level 3 - - - - - font-variant-position - - CSS Fonts Level 3 - - - - - font-variant-caps - - CSS Fonts Level 3 - - - - - font-variant-numeric - - CSS Fonts Level 3 - - - - - font-variant-alternates - - CSS Fonts Level 3 - - - - - font-variant-east-asian - - CSS Fonts Level 3 - - - - - font-feature-settings - - CSS Fonts Level 3 - - - - - font-variation-settings - - CSS Fonts Level 4 - - - - - -gtk-dpi - Number - defaults to screen resolution - - - Font Shorthands - - font - - CSS Fonts Level 3 - - CSS allows line-height, etc - - - font-variant - - CSS Fonts Level 3 - - - - Text Caret Properties - - caret-color - - CSS Basic User Interface Level 3 - - CSS allows an auto value - - - -gtk-secondary-caret-color - Color - used for the secondary caret in bidirectional text - - Text Decoration Properties - - letter-spacing - - CSS Text Level 3 - - - - - text-decoration-line - - CSS Text Decoration Level 3 - - CSS allows overline - - - text-decoration-color - - CSS Text Decoration Level 3 - - - - - text-decoration-style - - CSS Text Decoration Level 3 - - CSS allows dashed and dotted - - - text-shadow - - CSS Text Decoration Level 3 - - - - Text Decoration Shorthands - - text-decoration - - CSS Text Decoration Level 3 - - - - Icon Properties - - -gtk-icon-source - Image, builtin or none - used for builtin icons in buttons and expanders - - - -gtk-icon-size - Length - size used for builtin icons in buttons and expanders - - - -gtk-icon-style - requested, regular or symbolic - preferred style for application-loaded icons - - - -gtk-icon-transform - - Transform list or none - - applied to builtin and application-loaded icons - - - -gtk-icon-palette - Color palette, as explained above - used to recolor symbolic icons - - - -gtk-icon-shadow - - Shadow or none - - applied to builtin and application-loaded icons - - - -gtk-icon-filter - - Filter value list or none - - applied to builtin and application-loaded icons - - - Box Properties - - transform - - CSS Transforms Level 2 - - - - - min-width - - CSS Box Model Level 3 - - CSS allows percentages - - - min-height - - CSS Box Model Level 3 - - CSS allows percentages - - - margin-top - - CSS Box Model Level 3 - - CSS allows percentages or auto - - - margin-right - - CSS Box Model Level 3 - - CSS allows percentages or auto - - - margin-bottom - - CSS Box Model Level 3 - - CSS allows percentages or auto - - - margin-left - - CSS Box Model Level 3 - - CSS allows percentages or auto - - - padding-top - - CSS Box Model Level 3 - - CSS allows percentages - - - padding-right - - CSS Box Model Level 3 - - CSS allows percentages - - - padding-bottom - - CSS Box Model Level 3 - - CSS allows percentages - - - padding-left - - CSS Box Model Level 3 - - CSS allows percentages - - - Box Shorthands - - margin - - CSS Box Model Level 3 - - a 'four sides' property - - - padding - - CSS Box Model Level 3 - - a 'four sides' property - - - Border Properties - - border-top-width - - CSS Backgrounds and Borders Level 3 - CSS allows other values - - - border-right-width - - CSS Backgrounds and Borders Level 3 - - CSS allows other values - - - border-bottom-width - - CSS Backgrounds and Borders Level 3 - - CSS allows other values - - - border-left-width - - CSS Backgrounds and Borders Level 3 - - CSS allows other values - - - border-top-style - - CSS Backgrounds and Borders Level 3 - - - - - border-right-style - - CSS Backgrounds and Borders Level 3 - - - - - border-bottom-style - - CSS Backgrounds and Borders Level 3 - - - - - border-left-style - - CSS Backgrounds and Borders Level 3 - - - - - border-top-right-radius - - CSS Backgrounds and Borders Level 3 - - - - - border-bottom-right-radius - - CSS Backgrounds and Borders Level 3 - - - - - border-bottom-left-radius - - CSS Backgrounds and Borders Level 3 - - - - - border-top-left-radius - - CSS Backgrounds and Borders Level 3 - - - - - border-top-color - - CSS Backgrounds and Borders Level 3 - - - - - border-right-color - - CSS Backgrounds and Borders Level 3 - - - - - border-bottom-color - - CSS Backgrounds and Borders Level 3 - - - - - border-left-color - - CSS Backgrounds and Borders Level 3 - - - - - border-image-source - - CSS Backgrounds and Borders Level 3 - - - - - border-image-repeat - - CSS Backgrounds and Borders Level 3 - - - - - border-image-slice - - CSS Backgrounds and Borders Level 3 - - a 'four sides' property - - - border-image-width - - CSS Backgrounds and Borders Level 3 - - a 'four sides' property - - - Border Shorthands - - border-width - - CSS Backgrounds and Borders Level 3 - - a 'four sides' property - - - border-style - - CSS Backgrounds and Borders Level 3 - - a 'four sides' property - - - border-color - - CSS Backgrounds and Borders Level 3 - - a 'four sides' property - - - border-top - - CSS Backgrounds and Borders Level 3 - - - - - border-right - - CSS Backgrounds and Borders Level 3 - - - - - border-bottom - - CSS Backgrounds and Borders Level 3 - - - - - border-left - - CSS Backgrounds and Borders Level 3 - - - - - border - - CSS Backgrounds and Borders Level 3 - - - - - border-radius - - CSS Backgrounds and Borders Level 3 - - - - - border-image - - CSS Backgrounds and Borders Level 3 - - - - - Outline Properties - - outline-style - - CSS Basic User Interface Level 3 - - initial value is none, auto is not supported - - - outline-width - - CSS Basic User Interface Level 3 - - - - - outline-color - - CSS Basic User Interface Level 3 - - initial value is currentColor, invert is not supported - - - outline-offset - - CSS Basic User Interface Level 3 - - - - - Outline Shorthands - - outline - - CSS Basic User Interface Level 3 - - - - - Background Properties - - background-color - - CSS Backgrounds and Borders Level 3 - - - - - background-clip - - CSS Backgrounds and Borders Level 3 - - - - - background-origin - - CSS Backgrounds and Borders Level 3 - - - - - background-size - - CSS Backgrounds and Borders Level 3 - - - - - background-position - - CSS Backgrounds and Borders Level 3 - - - - - background-repeat - - CSS Backgrounds and Borders Level 3 - - - - - background-image - - CSS Backgrounds and Borders Level 3 - - not supported: urls without quotes, colors in crossfades - - - box-shadow - - CSS Backgrounds and Borders Level 3 - - - - - background-blend-mode - - CSS Compositing and Blending Level 1 - - only affects multiple backgrounds - - - Background Shorthands - - background - - CSS Backgrounds and Borders Level 3 - - - - - Transition Properties - - transition-property - - CSS Transitions - - - - - transition-duration - - CSS Transitions - - - - - transition-timing-function - - CSS Transitions - - - - - transition-delay - - CSS Transitions - - - - - Transition Shorthands - - transition - - CSS Transitions - - - - - Animation Properties - - animation-name - - CSS Animations Level 1 - - - - - animation-duration - - CSS Animations Level 1 - - - - - animation-timing-function - - CSS Animations Level 1 - - - - - animation-iteration-count - - CSS Animations Level 1 - - - - - animation-direction - - CSS Animations Level 1 - - - - - animation-play-state - - CSS Animations Level 1 - - - - - animation-delay - - CSS Animations Level 1 - - - - - animation-fill-mode - - CSS Animations Level 1 - - - - - Animation Shorthands - - animation - - CSS Animations Level 1 - - - - - Table-related Properties - - border-spacing - - CSS Table Level 3 - - respected by GtkBox and GtkGrid - - - -
- - - diff --git a/docs/reference/gtk/css-properties.md b/docs/reference/gtk/css-properties.md new file mode 100644 index 0000000000..7e6fcdedaa --- /dev/null +++ b/docs/reference/gtk/css-properties.md @@ -0,0 +1,238 @@ +# GTK CSS Properties + +GTK supports CSS properties and shorthands as far as they can be applied +in the context of widgets, and adds its own properties only when needed. +All GTK-specific properties have a -gtk prefix. + +## Basic types + +All properties support the following keywords: inherit, initial, unset, +with the same meaning as defined in the +[CSS Cascading and Inheritance](https://www.w3.org/TR/css3-cascade/#defaulting-keywords) +spec. + +The following units are supported for basic datatypes: + +Length + : px, pt, em, ex, rem, pc, in, cm, mm, calc() +Percentage + : %, calc() +Angle + : deg | grad | turn, calc() +Time + : s | ms, calc() + +Length values with the em or ex units are resolved using the font +size value, unless they occur in setting the font-size itself, in +which case they are resolved using the inherited font size value. + +The rem unit is resolved using the initial font size value, which is +not quite the same as the CSS definition of rem. + +The calc() notation adds considerable expressive power. There are limits +on what types can be combined in such an expression (e.g. it does not make +sense to add a number and a time). For the full details, see the +[CSS3 VAlues and Units](https://www.w3.org/TR/css3-values/#calc-notation) +spec. + +A common pattern among shorthand properties (called 'four sides') is one +where one to four values can be specified, to determine a value for each +side of an area. In this case, the specified values are interpreted as +follows: + +4 values: + : top right bottom left +3 values: + : top horizontal bottom +2 values: + : vertical horizontal +1 value: + : all + +## Colors + +GTK extends the CSS syntax with several additional ways to specify colors. + +The first is a reference to a color defined via a @define-color rule in CSS. +The syntax for @define-color rules is as follows: + +``` +@define-color Name Color +``` + +To refer to the color defined by a @define-color rule, prefix the name with @. + +GTK also supports color expressions, which allow colors to be transformed to +new ones. Color expressions can be nested, providing a rich language to +define colors. Color expressions resemble functions, taking 1 or more colors +and in some cases a number as arguments. + +`lighter(Color)` + : produces a brigher variant of Color +`darker(Color)` + : produces a darker variant of Color +`shade(Color, Number)` + : changes the lightness of Color. The number ranges from 0 for black to 2 for white. +`alpha(Color, Number)` + : replaces the alpha value of color with number (between 0 and 1) +`mix(Color1, Color2, Number)` + : interpolates between the two colors + +## Images + +GTK extends the CSS syntax for images and also uses it for specifying icons. +To load a themed icon, use + +``` +-gtk-icontheme(Name) +``` + +The specified icon name is used to look up a themed icon, while taking into +account the values of the -gtk-icon-palette property. This kind of image is +mainly used as value of the -gtk-icon-source property. + +Symbolic icons from the icon theme are recolored according to the +-gtk-icon-palette property, which defines a list of named colors. +The recognized names for colors in symbolic icons are error, warning +and success. The default palette maps these three names to symbolic +colors with the names @error_color, @warning_color and @success_color +respectively. The syntax for defining a custom palette is a comma-separated +list of name-color pairs, e.g. + +``` +success blue, warning #fc3, error magenta +``` + +Recoloring is sometimes needed for images that are not part of an icon theme, +and the + +``` +-gtk-recolor(uri, palette) +``` + +syntax makes this available. -gtk-recolor requires a url as first argument. +The remaining arguments specify the color palette to use. If the palette is +not explicitly specified, the current value of the -gtk-icon-palette property +is used. + +GTK supports scaled rendering on hi-resolution displays. This works best if +images can specify normal and hi-resolution variants. From CSS, this can be +done with + +``` +-gtk-scaled(Image1, Image2) +``` + +## GTK CSS Properties + +| Property | Reference | Notes | +|:-----------|:----------|:------| +|color | [CSS Color Level 3](https://www.w3.org/TR/css3-color/#foreground) | | +|opacity | [CSS Color Level 3](https://www.w3.org/TR/css3-color/#opacity) | | +|filter | [CSS Filter Effect Level 1](https://drafts.fxtf.org/filters/#FilterProperty) | | +|font-family | [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-family-prop) | defaults to gtk-font-name setting | +|font-size | [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-size-prop) | defaults to gtk-font-name setting | +|font-style | [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-style-prop) | | +|font-variant| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#descdef-font-variant) | only CSS2 values supported | +|font-weight | [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-weight-prop) | | +|font-stretch| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-stretch-prop) | | +|font-kerning| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-kerning-prop) | | +|font-variant-ligatures| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-variant-ligatures-prop) | | +|font-variant-position| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-variant-position-prop) | | +|font-variant-caps| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-variant-position-prop) | | +|font-variant-numeric| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-variant-numeric-prop) | | +|font-variant-alternates| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-variant-alternates-prop) | | +|font-variant-east-asian| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-variant-east-asian-prop) | | +|font-feature-settings| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-feature-settings-prop) | | +|font-variation-settings| [CSS Fonts Level 4](https://www.w3.org/TR/css-fonts-4/#font-variation-settings-def) | | +|-gtk-dpi|[Number](https://www.w3.org/TR/css3-values/#number-value) | defaults to screen resolution | +|font| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-prop) | CSS allows line-height, etc | +|font-variant| [CSS Fonts Level 3](https://www.w3.org/TR/css3-fonts/#font-variant-prop) | | +|caret-color|[CSS Basic User Interface Level 3](https://www.w3.org/TR/css3-ui/#caret-color) | CSS allows an auto value | +|-gtk-secondary-caret-color|[Color](https://www.w3.org/TR/css-color-3/#valuea-def-color) | used for the secondary caret in bidirectional text | +|letter-spacing| [CSS Text Level 3](https://www.w3.org/TR/css3-text/#letter-spacing) | | +|text-decoration-line| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-decoration-line-property) | CSS allows overline | +|text-decoration-color| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-decoration-color-property) | | +|text-decoration-style| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-decoration-style-property) | CSS allows dashed and dotted | +|text-shadow| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-shadow-property) | | +|text-decoration| [CSS Text Decoration Level 3](https://www.w3.org/TR/css-text-decor-3/#text-decoration-property) | | +|-gtk-icon-source| [Image](https://www.w3.org/TR/css-backgrounds-3/#typedef-image), `builtin` or `none` | used for builtin icons in buttons and expanders | +|-gtk-icon-size| [Length](https://www.w3.org/TR/css3-values/#length-value) | size used for builtin icons in buttons and expanders | +|-gtk-icon-style| `requested`, `regular` or `symbolic` | preferred style for application-loaded icons | +|-gtk-icon-transform| [Transform list](https://drafts.csswg.org/css-transforms-1/#typedef-transform-list) or `none` | applied to builtin and application-loaded icons | +|-gtk-icon-palette| Color palette, as explained above | used to recolor symbolic icons | +|-gtk-icon-shadow| [Shadow](https://www.w3.org/TR/css-backgrounds-3/#typedef-shadow) or `none` | applied to builtin and application-loaded icons | +|-gtk-icon-filter| [Filter value list](https://www.w3.org/TR/filter-effects-1/#typedef-filter-value-list) or `none` | applied to builtin and application-loaded icons | +|transform| [CSS Transforms Level 2](https://drafts.csswg.org/css-transforms-2/) | | +|min-width| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#min-width) | CSS allows percentages | +|min-height| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#min-height) | CSS allows percentages | +|margin-top| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#margin-top) | CSS allows percentages or auto | +|margin-right| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#margin-right) | CSS allows percentages or auto | +|margin-bottom| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#margin-bottom) | CSS allows percentages or auto | +|margin-left| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#margin-left) | CSS allows percentages or auto | +|padding-top| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#padding-top) | CSS allows percentages | +|padding-right| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#padding-right) | CSS allows percentages | +|padding-bottom| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#padding-bottom) | CSS allows percentages | +|padding-left| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#padding-left) | CSS allows percentages | +|margin| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#margin) | a 'four sides' property | +|padding| [CSS Box Model Level 3](https://www.w3.org/TR/css3-box/#padding) | a 'four sides' property | +|border-top-width| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-width) | CSS allows other values | +|border-right-width| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-width) | CSS allows other values | +|border-bottom-width| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-width) | CSS allows other values | +|border-left-width| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-width) | CSS allows other values | +|border-top-style| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-style) | | +|border-right-style| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-style) | | +|border-bottom-style| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-style) | | +|border-left-style| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-style) | | +|border-top-right-radius| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-radius) | | +|border-bottom-right-radius| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-radius) | | +|border-bottom-left-radius| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-radius) | | +|border-top-left-radius| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-radius) | | +|border-top-color| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-color) | | +|border-right-color| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-color) | | +|border-bottom-color| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-color) | | +|border-left-color| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-color) | | +|border-image-source| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-image-source) | | +|border-image-repeat| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-image-repeat) | | +|border-image-slice| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-image-slice) | a 'four sides' property | +|border-image-width| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-image-width) | a 'four sides' property | +|border-width| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-width) | a 'four sides' property | +|border-style| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#the-border-style) | a 'four sides' property | +|border-color| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#border-color) | a 'four sides' property | +|border-top| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#border-top) | | +|border-right| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#border-right) | | +|border-bottom| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#border-bottom) | | +|border-left| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#border-left) | | +|border| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#border) | | +|border-radius| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#border-radius) | | +|border-image| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#border-image) | | +|outline-style| [CSS Basic User Interface Level 3](https://www.w3.org/TR/css3-ui/#outline-style) | initial value is none, auto is not supported | +|outline-width| [CSS Basic User Interface Level 3](https://www.w3.org/TR/css3-ui/#outline-width) | | +|outline-color| [CSS Basic User Interface Level 3](https://www.w3.org/TR/css3-ui/#outline-color) | initial value is currentColor, invert is not supported | +|outline-offset| [CSS Basic User Interface Level 3](https://www.w3.org/TR/css3-ui/#outline-offset) | | +|outline| [CSS Basic User Interface Level 3](https://www.w3.org/TR/css3-ui/#propdef-outline) | | +|background-color| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-color) | | +|background-clip| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-clip) | | +|background-origin| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-origin) | | +|background-size| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-size) | | +|background-position| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-position) | | +|background-repeat| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-repeat) | | +|background-image| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background-image) | not supported: urls without quotes, colors in crossfades | +|box-shadow| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#box-shadow) | | +|background-blend-mode| [CSS Compositing and Blending Level 1](https://www.w3.org/TR/compositing-1/#propdef-background-blend-mode) | only affects multiple backgrounds | +|background| [CSS Backgrounds and Borders Level 3](https://www.w3.org/TR/css3-background/#background) | | +|transition-property| [CSS Transitions](https://www.w3.org/TR/css3-transitions/#transition-property) | | +|transition-duration| [CSS Transitions](https://www.w3.org/TR/css3-transitions/#transition-duration) | | +|transition-timing-function| [CSS Transitions](https://www.w3.org/TR/css3-transitions/#transition-timing-function) | | +|transition-delay| [CSS Transitions](https://www.w3.org/TR/css3-transitions/#transition-delay) | | +|transition| [CSS Transitions](https://www.w3.org/TR/css3-transitions/#transition) | | +|animation-name| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-name) | | +|animation-duration| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-duration) | | +|animation-timing-function| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-timing-function) | | +|animation-iteration-count| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-iteration-count) | | +|animation-direction| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-direction) | | +|animation-play-state| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-play-state) | | +|animation-delay| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-delay) | | +|animation-fill-mode| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation-fill-mode) | | +|animation| [CSS Animations Level 1](https://www.w3.org/TR/css3-animations/#animation) | | +|border-spacing| [CSS Table Level 3](https://www.w3.org/TR/css-tables-3/#border-spacing-property) | respected by GtkBox and GtkGrid | diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml index 6905a4ea42..a0ec153bbd 100644 --- a/docs/reference/gtk/gtk4-docs.xml +++ b/docs/reference/gtk/gtk4-docs.xml @@ -378,6 +378,7 @@ Theming in GTK + diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build index b8ef12a6bd..b30bbb91b7 100644 --- a/docs/reference/gtk/meson.build +++ b/docs/reference/gtk/meson.build @@ -343,7 +343,6 @@ content_files = [ 'broadway.xml', 'building.xml', 'compiling.xml', - 'css-overview.xml', 'glossary.xml', 'gtk4-broadwayd.xml', 'gtk4-builder-tool.xml', @@ -382,7 +381,9 @@ expand_content_md_files = [ 'migrating-3to4.md', 'actions.md', 'input-handling.md', - 'drawing-model.md' + 'drawing-model.md', + 'css-overview.md', + 'css-properties.md' ] types_conf = configuration_data() -- 2.30.2